<html>
<!-- $LastChangedDate: 2009-11-22 22:39:11 -0500 (Sun, 22 Nov 2009) $ -->
<!-- Copyright (C) 2004,2009 Jim Brooks http://www.palomino3d.org -->
<head>
<title>Palomino - Game Module (Lua and C++)</title>
<link rel='stylesheet' type='text/css' href='docs.css'>
<link rel='icon' type='image/png' href='images/favicon.png'/>
</head>
<body>

<!-- ----------------------------------------------------------------------- -->
<h1>Palomino - Game Module (Lua and C++)</h1>
<p>
&copy;2004,2009&nbsp;&nbsp;Jim E. Brooks
&nbsp;&nbsp;<a href='http://www.palomino3d.org'>http://www.palomino3d.org</a>
</p>
<hr>
<ul>
  <li><a href='index.html'>Index</a></li>
  <li><a href='#Overview'>Overview</a></li>
  <li><a href='#Examples of Game Logic'>Examples of Game Logic</a></li>
  <li><a href='#Implementation Partitioned Across Lua and C++'>Implementation Partitioned Across Lua and C++</a></li>
  <li><a href='#Actors'>Actors</a></li>
  <li><a href='#Actor Events'>Actor Events</a></li>
      <ul>
        <li><a href='#DestroyObject Event'>DestroyObject Event</a></li>
        <li><a href='#Collision-Detection Event'>Collision-Detection Event</a></li>
      </ul>
  <li><a href='#C++ Support for Lua'>C++ Support for Lua</a></li>
  <li><a href='#HUD'>HUD</a></li>
  <li><a href='#Missiles'>Missiles</a></li>
</ul>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Overview'></a>
<h2>Overview</h2>
<p><!--date-->[2008/11]</p>
<p>
Most of the game logic shall be written in Lua.
The central concept is the <i>actor</i> (game entity).
</p>
<p><font size='-1'>
Unlike old versions, there is no C++ Actor class.
</font></p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Examples of Game Logic'></a>
<h2>Examples of Game Logic</h2>
<p><!--date-->[2008/10]</p>

<h3>SAM detects and fires at player</h3>
<ol>
  <li>SAM actor constructed during mission startup</li>
  <li>SAM actor listens for new actors to appear</li>
  <li>player is notified by HUD if within SAM's radar radius</li>
  <li>SAM actor tries to detect enemy aircraft using radar (exclude friendly aircraft)</li>
  <li>SAM actor selects an enemy</li>
  <li>player is notified by HUD if SAM has locked-on</li>
  <li>SAM actor fires missile when radar-lock becomes strong</li>
</ol>

<h3>New enemy aircraft is spawned</h3>
<ol>
  <li>AircraftActor is constructed</li>
  <li>Enemy's avionics builds initial list of hostile actors (includes player)</li>
  <li>Enemy's avionics tracks certain kinds of actors (aircraft, missiles, radars)</li>
  <li>Enemy AI reacts to nearest actor</li>
  <li>Enemy or its friend may destroy nearest actor, so reassess threating actors</li>
</ol>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Implementation Partitioned Across Lua and C++'></a>
<a name='Implementation Split Across Lua and C++'></a>
<h2>Implementation Partitioned Across Lua and C++</h2>
<p><!--date-->[2008/10]</p>
<p>
A goal is to implement the game logic in Lua as much as possible.
The C++ side shall have supporting subroutines.
But the notion of <i>actors</i> and a <i>game class</i> only exist in Lua.
</p>
<p>
Writing signficant parts in C++ would be difficult to implement (explained below).
Even without those difficulties, the result would be a disorganized implementation.
</p>
<h3>Difficulties in alternative implementation based on C++ classes</h3>
<p>
<font size='-1'>The C++ simulator and Lua are based on reference-counting.
One design that was considered was to implement actor classes in C++
which are exported to Lua, and then Lua would've had classes based on them.
Having actor objects existing in both C++ and Lua would have complications.
If a C++ MissileActor destroys an AircraftActor, Lua may be holding
a reference to the AircraftActor.  By design, C++ cannot call Lua,
so Lua would have to actively poll a "zombie list" produced by C++
in order for Lua to release references.
</font></p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Game Class'></a>
<a name='Game class'></a>
<h2>Game Class</h2>
<p><!--date-->[2008/10]</p>
<p>
The notion of a <i>Game class</i> exists only in Lua.
</p>
<h3>Requirements of the Game class</h3>
<ul>
  <li>is THE container of Actors (C++ doesn't know nor hold references to them)</li>
  <li>can decide to attach/detach Actors</li>
  <li>responds to network commands to attach/detach Actors</li>
</ul>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Actors'></a>
<h2>Actors</h2>
<p><!--date-->[2008/10]</p>
<h3>Requirements and characteristics of Actors</h3>
<ul>
  <li>contained in the <a href='#Game'>Game class</a></li>
  <li>contains an Object or derivative</li>
  <li>aware of each other by the <a href='#Game'>Game class</a></li>
</ul>
<h3>Examples of Actor Classes</h3>
<ul>
  <li>generic</li>
  <li>aircraft</li>
  <li>missile</li>
  <li>radar</li>
  <li>SAM</li>
  <li>vehicle</li>
</ul>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Actor Events'></a>
<h2>Actor Events</h2>
<p><!--date-->[2008/11]</p>

<a name='DestroyObject Event'></a>
<h3>DestroyObject Event</h3>
<p>
Both C++ and Lua can hold references to an Object.
If one side decides to destroy an Object,
an event must be broadcast to unreference the Object in all containers.
</p>
<p>
See <a href='rules.html#DestroyObject Event'>DestroyObject Event</a>.
</p>

<a name='Collision-Detection Event'></a>
<h3>Collision-Detection Event</h3>
<p>
C++ does collision-detection.
So, when Lua creates a missile actor, Lua has to poll Dyna::IfCollision()
of an Actor's underlying Object/Dyna.
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='C++ Support for Lua'></a>
<h2>C++ Support for Lua</h2>
<p><!--date-->[2008/10]</p>
<p>
The C++ side of the simulator provides subroutines to support the Lua game logic.
C++ is used for subroutines that must be executed every frame
or cannot be implemented in Lua.
</p>
<p>
C++ knows nothing about game concepts such as actors.
C++ manipulates an Aircraft without knowing it is part of a Lua Actor.
</p>
<p>
Example list of specific C++ subroutines for game logic:
</p>
<ul>
  <li>HUD widgets (target boxes)</li>
  <li>Controller class that animates an Object every frame (for missiles and guns)</li>
  <li>sends/receives commands across network (which Lua understands and processes)</li>
  <li>etc</li>
</ul>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Missiles'></a>
<h2>Missiles</h2>
<p><!--date-->[2008/10]</p>
<ul>
  <li>NOP if no radar lock or Craft has no more missiles</li>
  <li>create Object that inherits launching Craft's matrix</li>
  <li>create SmokeTrailParticleSystem</li>
  <li>register tick functor to animate missile (see Guidance)</li>
  <li>tick functor: create new particles where missile has moved to</li>
  <li>tick functor: do collision-detection of missile</li>
  <li>tick functor: check if target dropped chaff, randomly go off-course</li>
  <li>tick functor: if hit: start ExplosionParticleSystem</li>
  <li>tick functor: if hit: remove target from Game's target list</li>
</ul>

<h3>Guidance</h3>
<p><!--date-->[2007/10:V2]</p>
<p>
A basic guidance algorithm is:
</p>
<ol>

<li>Roll left.
</li>

<li>If angle between up vector (+Y) and target increased,
rolling left was a mistake, so roll right.
</li>

<li>Continue above steps until angle reaches zero.
</li>

<li>Likewise, try to pitch up or down
until the chaser's forward vector (Z) is pointing at the target.
</li>

</ol>

<p>
To avoid flip-flopping and jittering, the switching of maneuvers
needs to be moderated and have a tolerance for small angles.
For N frames, continue the same maneuver.
</p>

<!-- ********************************* END ********************************* -->
<hr>
<p align='center'>
<font size='-2'>
<!-- hhmts start -->
Last modified: Sun Nov 22 21:22:58 CST 2009
<!-- hhmts end -->
</font>
</p>

</body>
</html>
